<div id="copy">

<div id="sidebar">
	<hr/>
	<a href="#configuration">Configuration</a>
	<hr/>
	<a href="#copy">Copy</a>
	<hr/>
	<a href="#snippet">Snippet</a>
	<hr/>
	<a href="#theme">Theme</a>
	<hr/>
	<a href="#output">HTML Output</a>
	<hr/>
</div>

<div id="bodyCopy">
	
	<p>You start Gobl by using the "run" flag:
	<ol>
		<li><span id="code">gobl -r=cms</span> starts the CMS where the web administrators create the web site (initial admin user is "root" and password is "root" also, minus the quotes) and
		</li>
		<li><span id="code">gobl -r=ws</span> starts the web server where Gobl serves the web pages (created in #1) to the web site visitors. Starting the CMS will by default starts the web server too. 
		</li>
	</ol>
	</p>
	<p>The word Gobl may be loosely used to mean either of the two, depending on context, and this page focuses on #1.  The page on Deployment focuses on #2.
	</p>
	
	<span id="floatRight"><img src="/img/cc-by-beggs-flickr-281194868.jpg" width=280px alt="Documentation"/></span>
	
	<h3 id="configuration">Configuration</h3>
	<p>Server configuration 
	values are set in the file config.json.  At the moment there is no need yet for configuration setting from the GUI, although this may change in the future.  You can use your favourite text editor (e.g. vi, nano, etc) to edit the file and please keep in mind you are responsible to ensure valid JSON format in the configuration values.  For example, please do not forget to escape the special characters.
	</p>
	<h4><em>OS Path</em></h4>
	<p>OS path follows OS-specific forward or backward slash convention and the path can be absolute or relative.
	</p>
	<h4><em>HTTP and HTTPS</em></h4>
	<p>HTTP mode and HTTPS mode are mutually exclusive in Gobl by design.  I think if the use case is for app server, then I might as well go HTTPS all the way.  If just to serve web pages, then I am not sure why anybody would want to run both HTTPS and HTTP at the same time.  So if ServeTLS is true, then Gobl is serving HTTPS only; if false, HTTP only.
	</p>
	<h4><em>Language Support</em></h4>
	<p>Gobl is designed from the ground up to support multiple languages.  The list of supported language is calculated automatically, but one default language must be correctly planned in the configuration file.  Each template is associated with a language using the respective two-letter ISO code.  For the website default language, the templates must be complete.  For non-default language, if there are missing translated templates, Gobl will use the default language templates.
	</p>
	<p>Take note that language support for Gobl CMS and language support for the web site that you produce using Gobl is not the same, although for simplicity sake the files happen to be stored in the same directories / folders.
	</p>
	<p>For localisation of your web site, the only files you need to translate are your:
		<ol>
			<li>"Copy" files</li>
			<li>"Snippet" files whose file names start with "Site".  (The other snippet files are used for internal Gobl work or for CMS GUI.</li>
		</ol>
	</p>
	
	<h3 id="copy">Copy</h3>
	
	<p>Copy is stored in Gobl in HTML markup format along with relevant meta-data for the copy.  Copy + copy meta-data + <a href="#snippet">snippets</a> = web page.  I use the word 'copy' loosely; you can have non-text inside copy.
	</p>
	<p>The edit web GUI (CMS mode) consists of the following fields.
	</p>
	<ul>
		<li>Cid / Copy ID: Cid is the user-defined URL.  It can only contain valid alphanumeric characters.  Hyphen / dash is of course allowed.  Underscore is also allowed.  You must enter valid URL; Gobl does not prevent you from entering weird URL.</li>
		<li>Copy: This is the HTML markup for the page copy.  You must enter valid HTML markup.  (For long copy, you should prep it in an HTML editor and then paste here.)</li>
		<li>SEO Tags: This is the HTML markup that goes into the head tag of the HTML under the meta tag.  Used for SEO consumption.  It can contain several meta tags (e.g. for description, keywords, author, etc), but it needs to be valid HTML meta markup.</li>
		<li>Lang / Language: Gobl is language agnostic, so this flag is used to tell Gobl what language context the copy is supposed to have to use which language-specific layout and/or site navigation menu.</li>
		<li>CopyDate: If date is not empty, then the copy is a date-relevant copy.  For example for news or blog. The date is used for reverse chronological sorting on blog view.</li>
		<li>UsesOwnLayout: If true, the Copy field above must contain the full HTML markup of a valid page and therefore can use any layout it wants for custom page.  This accommodate custom site that uses multiple layouts.</li>
	</ul>
	<p>Copies are served from memory.  In CMS mode, the copies in memory are backed up into a set of HTML and JSON, which are also editable using a text editor, e.g. vi or nano.
	</p>
	<p>Every page that Gobl serves need to have the "Copy" structure defined, including the home page.  Home page url handler is by default equals the default language code.  For example, if gobl.me is translated to French, then the French home page would be gobl.me/fr, while the default home page is gobl.me/en which also accepts gobl.me.
	</p>
	
	<h3 id="snippet">Snippet</h3>
	
	<p>Conceptually, a snippet is just text that will invoke or be invoked in the assembly process of an HTML page.  Gobl uses the word "snippet" loosely to mean the following.
	</p>
	<ul>
		<li>HTML recipe: Just like in cooking, the recipe defines what goes into the HTML page structure.  I.e. it defines which other texts it needs to <em>invoke</em> to assemble the HTML page.  For example, the following is a clip from the "layout" snippet.
			<blockquote><span id="code">&lt;!--SiteHeader--&gt; <br/> &lt;!--SiteNav--&gt; <br/> &lt;!--Copy--&gt;  <br/> &lt;!--SiteFooter--&gt;</span>
			</blockquote>
			<p>They are in HTML comment format so if you do not use that particular component / ingredient, the HTML output will not show anything.  If you use the component / ingredient, Gobl will substitute them.  The "underscore" convention is explained elsewhere.
			</p>
		</li>
		<li>HTML ingredient: Just like in cooking, the ingredient defines the text that will be <em>invoked</em> during the HTML assembly process. Each HTML snippet / ingredient, in turn, can define almost anything.  It can define site navigation menu, error message, form definition, etc.  For example, you get to define your logo, tagline, etc in the header component / ingredient which will then be used to substitute <span id="code">&lt;!--SiteHeader--&gt;</span> in the HTML assembly process.
		</li>
	</ul>
	<p>The edit web GUI (CMS mode) consists of the following fields.
	</p>
	<ul>
		<li>Tid / Snippet Id: Name of the snippet, i.e. how it is called inside the server.  This field is read-only in the GUI.</li>
		<li>Language: Snippet's language.  This field is read-only in the GUI.</li>
		<li>Snippet: This is the HTML markup for the page content.  You must enter valid HTML markup.  (For long content, you should prep it in an HTML editor and then paste here.)  Keep in mind, that as long as it is valid HTML code, one snippet can consist of reasonably long and complex markup.</li>
	</ul>
	<p>Snippets are served from memory.  In CMS mode, the copies in memory are backed up into one directory / folder, named after the language ISO code.  And then the snippets are backed up into text files - one file per snippet.
	</p>
	<p>Snippet names are <em>hard coded</em> into the Go source codes, so those are reserved names - please do not change the snippet file names.  They are also case sensitive.
	</p>
	<ol>
		<li>Files that start with the word "Site" are used for defining your web site's pages.
			<p>As far as general Gobl use is concerned, these are the only snippets that need modifying to customise your web site look and feel.  The page administration panel only lists these snippets.
			</p>
		</li>
		<li>All other snippet files are used for defining Gobl CMS web app (CMS mode).
			<p>Tweak these only if you want to translate Gobl CMS into other languages.  Editing these files into invalid HTML or not following Gobl convention may break the system. Otherwise, you probably do not need to touch these.  If you do, then you need to use CLI and text editor.  (Alternatively, you can also use the CMS GUI but you need to hand type the URL, so you might as well use CLI.)
			</p>
		</li>
	</ol>
	<p>Just like "copy", a "snippet" is just data to Gobl.  Gobl CMS itself is bootstrapped using snippets and copies.
	</p>
	
	<h3 id="theme">Theme</h3>
	
	<p>Customising the look and feel of a Gobl web site involves two things.</p>
	<ul>
		<li>Updating snippets
			<p>Edit or replace relevant snippets to use the updated or newresource files for the customisations.  If you are theming Gobl yourself, then you can edit it using the web UI. Alternatively, use your HTML editor and then replace Gobl's default files. You only need to touch the snippets that start with "Site".
			</p>
		</li>
		<li>Updating resource files
			<p>Replace or add the resource files (CSS/JS/IMG) in relevant Gobl directories / folders to respond to the newly updated snippets above.
			</p>
		</li>
		<li>Ensuring contents reflect the theme
			<p>Changes on resource files (e.g. CSS) will need to be retroactively checked in the contents.</p>
		</li>
	</ul>
	<p>Since the snippets can use any valid JS, you can pretty much build up complex client-side JS app in the snippets.  Just load the JS in the resources folder.
	</p>
	
	<p>Gobl does not come with web GUI to manage third party themes.  Current assumption is that gobl users are mainly web designers who would want to develop their own custom design.  But maybe if there are enough designers out there who want to share their themes, some more documentation can be created.
	</p>
	
	<h3 id="output">HTML Output</h3>
	
	<p>Gobl serves HTML page that is assembled following a layout template / snippet that, in summary, looks something like this - clipped from the <span id="code">SiteLayout</span> definition file. (This, like any snippet, is user customisable.)<br/>
		<span id="code">
			&lt;head&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;title&gt;{Title}&lt;title/&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;!--SEOTags--&gt;
			&lt;head/&gt; <br/>
			&lt;body&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;!--SiteHeader--&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;!--SiteNav--&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;!--Copy--&gt; <br/>
			&nbsp;&nbsp;&nbsp;&nbsp;&lt;!--SiteFooter--&gt; <br/>
			&lt;/body&gt; <br/>
		</span>
	</p>
	<p>The "comment" looking portions are snippets or more accurately placeholders for where the snippets will be pasted in during the HTML assembly.  <span id="code">{Title}</span> is one of the properties of "copy".  The entire layout definition itself is actually a Gobl snippet that is called <span id="code">SiteLayout</span>.  The <span id="code">SiteLayout</span> definition file is needed for bootstrapping the web server.
	</p>
	
	<h4><em>Resource File / Static File</em></h4>
	
	<p>This is governed by the configuration of "FilePath" in Config.json.  Any supported file types need to be stored in the directory / folder specified in "FilePath".  They are served following the sub-directory / sub-folder structure identically.  For example, to access <span id="code">&lt;img src="/img/logo.png"/&gt;</span>, the file logo.png needs to be located in <span id="code">/FilePath/img/logo.png</span>.  Likewise for CSS, JS or any other file types.
	</p>
	<p>And you can also serve static HTML files as resource files and make Gobl as a simple web server.  Not sure why you want to do that, but it works.
	</p>
	
</div>

</div>
